Changesets

Introduction

As developers, we all know how crucial it is to keep our codebase organized and maintain a clear overview of the changes we make. That's where changesets come in. They're a powerful tool that helps us manage and track modifications effectively. In this documentation, we'll explore what changesets are and how they can benefit your project's development process.

What are Changesets?

Changesets are a structured way to group related code changes together. They act as a container that encapsulates a set of modifications made to your codebase. Each changeset typically includes a concise summary of the changes, references to relevant issues or pull requests, and any additional context that helps us understand the purpose and impact of the changes.

Benefits of Using Changesets

Using changesets offers several benefits that can enhance your development workflow:

1. Improved Collaboration: Changesets provide a clear and structured way to communicate changes to your team. By including relevant information and context, they facilitate better collaboration and reduce misunderstandings. Team members can quickly grasp the purpose and impact of each change, making collaboration smoother and more effective.

2. Streamlined Code Reviews: With changesets, code reviews become more efficient and focused. By summarizing the changes and providing references, reviewers can understand the scope and intent of a change more easily. This leads to faster iterations and higher-quality code reviews, saving time and effort for everyone involved.

3. Enforced Change Scopes: Changesets encourage the practice of making atomic and focused modifications. By grouping related changes together, they help maintain a clean and well-organized codebase. This promotes better code reasoning and makes it easier to isolate and resolve potential issues, reducing the risk of unintended consequences.

4. Easier Release Management: Changesets play a vital role in release management. They provide an organized overview of the changes that need to be included in a release. This simplifies the planning and coordination of the release process, ensuring that the right changes are incorporated into each release.

Installation & Configuration

• pnpm install --save-dev @changesets/cli changesets-gitlab
• pnpx changeset init
• Create a project access token in GitLab and add it to your CI/CD settings as CHANGESETS_TOKEN
  • Scopes: api
• Edit your .gitlab-ci.yml file to include the following jobs:

# Gesso is currently using node 18 alpine as the base image
# this is not a hard requirement but other confifurations may need to be updated
# to make your image work.
image: node:18-alpine

# Add the following variables to your CI/CD settings
# as required by the changesets-gitlab package
variables:
  GITLAB_TOKEN: $CHANGESETS_TOKEN

# Before script to install dependencies and configure the environment
# this is used in the jobs below adjust as needed
before_script: &base-before-script
  - corepack enable
  - corepack prepare pnpm@8.15.4 --activate
  - pnpm config set store-dir .pnpm-store
  - |
    {
      echo "@acromedia:registry=https://git.acromedia.com/api/v4/projects/1149/packages/npm/"
      echo "${CI_API_V4_URL#https?}/packages/npm/:_authToken=\${CI_JOB_TOKEN}"
      echo "${CI_API_V4_URL#https?}/projects/:_authToken=\${CI_JOB_TOKEN}"
      echo "${CI_API_V4_URL#https?}/projects/1149/packages/npm/:_authToken=\${CI_JOB_TOKEN}"
    } | tee -a ~/.npmrc
  - pnpm install --prefer-offline;
  # should not be needed once main has cached this correctly
  - pnpm cypress install

# Handle checking MR for changeset
changeset-check:
  needs: []
  stage: comment
  before_script:
    - corepack enable
    - corepack prepare pnpm@8.15.4 --activate
    - pnpm config set store-dir .pnpm-store
    - pnpm install --prefer-offline --filter gesso
  cache:
    - key:
        files:
          - pnpm-lock.yaml
      paths:
        - .pnpm-store
      policy: pull
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - pnpm changesets-gitlab comment

# Handle changeset release
release:
  stage: release
  cache:
    - key:
        files:
          - pnpm-lock.yaml
      paths:
        - .pnpm-store
      policy: pull
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  before_script:
    - apk add git
    - *base-before-script
  script:
    - pnpm changesets-gitlab
  variables:
    INPUT_PUBLISH: pnpm publish-packages
    # Optional: If you are publishing to a registry in a different project
    # you will need to whitelist the project access token in your registry repository
    # to all your codebase repository to access `Settings > CI/CD > Token Access`.
    # This is not needed if you are publishing to the same project as your codebase.
    NPM_TOKEN: ${CI_JOB_TOKEN}

Usage

When you want to make a change, you can create a new changeset by running the following command:

pnpx changeset

This will generate a new changeset file in the .changeset directory. You can then edit the changeset file to include a summary of the changes, references to relevant issues or pull requests, and any additional context that helps explain the purpose and impact of the changes. Commit the changeset file along with your code changes.

When you merge to your main branch, changesets will be automatically detected and a new release MR will be created. Upon merging that MR, the changeset will be published to the registry and the version will be bumped.

Further Information

To dive deeper into changesets and learn how to integrate them into your development workflow, we recommend referring to the official Changesets documentation. It provides comprehensive information, tutorials, and examples to help you get started and make the most out of this valuable tool.

For more detailed information, visit the Changesets Documentation.

Embrace changesets and unlock a whole new level of code management and collaboration within your team. Happy coding!